<para>
Prior to GTK+ 2.4, there were several APIs in use to create menus
- and toolbars. GTK+ itself included #GtkItemFactory, which was
+ and toolbars. GTK+ itself included <link
+ linkend="GtkItemFactory">GtkItemFactory</link>, which was
historically used in the GIMP; libgnomeui provided the gnome-ui
set of macros; libbonoboui provided a complex mechanism to do menu
merging across embedded components. GTK+ 2.4 includes a system
for creating menus and toolbars, with merging of items, based
- around the #GtkAction mechanism.
+ around the <link linkend="GtkAction">GtkAction</link> mechanism.
</para>
<section id="actions-and-action-groups">
<title>Actions and Action Groups</title>
<para>
- A #GtkAction represents an operation that the user can perform
- from the menus and toolbars of an application. It is similar to
- "verbs" in other menu systems. A #GtkAction has a name, which
- is its identifier, and it can have several widgets that
- represent it in the user interface. For example, an action for
- <symbol>EditCopy</symbol> can have a menu item as well as a
+ A <link linkend="GtkAction">GtkAction</link> represents an
+ operation that the user can perform from the menus and toolbars
+ of an application. It is similar to "verbs" in other menu
+ systems. A <link linkend="GtkAction">GtkAction</link> has a
+ name, which is its identifier, and it can have several widgets
+ that represent it in the user interface. For example, an action
+ for <symbol>EditCopy</symbol> can have a menu item as well as a
toolbar button associated to it. If there is nothing selected
in the document, the application can simply de-sensitize the
<symbol>EditCopy</symbol> action; this will cause both the menu
item and the toolbar button to be de-sensitized automatically.
Similarly, whenever the user selects the menu item or the
toolbar button associated to the <symbol>EditCopy</symbol>
- action, the corresponding #GtkAction object will emit an
+ action, the corresponding <link
+ linkend="GtkAction">GtkAction</link> object will emit an
"activate" signal.
</para>
<para>
- #GtkActionGroup is simply a group of #GtkAction objects. An
+ <link linkend="GtkActionGroup">GtkActionGroup</link> is simply a
+ group of <link linkend="GtkAction">GtkAction</link> objects. An
application may want to have several groups: one for global
actions such as "new document", "about", and "exit"; then one
group for each open document with actions specific to the
<title>User Interface Manager Object</title>
<para>
- #GtkUIManager is an object that can construct menu and toolbar
- widgets from an XML description. These widgets are in turn
- associated to corresponding actions and action groups.
+ <link linkend="GtkUIManager">GtkUIManager</link> is an object
+ that can construct menu and toolbar widgets from an XML
+ description. These widgets are in turn associated to
+ corresponding actions and action groups.
</para>
<para>
- #GtkUIManager supports merging of menus and toolbars for
- applications that have multiple components, each with separate
- sets of commands. For example, a word processor that can embed
- images may want to have toolbar buttons for Bold and Italic when
- the cursor is on a text block, but Crop and Brightness/Contrast
- buttons when the cursor is on an image. These actions, which
- change depending on the state of the application, can be merged
- and de-merged from a #GtkUIManager as appropriate.
+ <link linkend="GtkUIManager">GtkUIManager</link> supports
+ merging of menus and toolbars for applications that have
+ multiple components, each with separate sets of commands. For
+ example, a word processor that can embed images may want to have
+ toolbar buttons for Bold and Italic when the cursor is on a text
+ block, but Crop and Brightness/Contrast buttons when the cursor
+ is on an image. These actions, which change depending on the
+ state of the application, can be merged and de-merged from a
+ <link linkend="GtkUIManager">GtkUIManager</link> as appropriate.
</para>
</section>
<listitem>
<para>
Separate your existing GnomeUIInfo entries into normal
- actions, toggle actions, and radio actions, and then create a
- separate array of #GtkActionEntry structures for each
- group. This will allow you to create the necessary
- #GtkActionGroup objects. Note that this does not describe
- the actual "shape" that your menus and toolbars will have;
- it simply defines the set of commands that will appear in them.
+ actions, toggle actions, and radio actions, and then create
+ a separate array of <link
+ linkend="GtkActionEntry">GtkActionEntry</link> structures
+ for each group. This will allow you to create the necessary
+ <link linkend="GtkActionGroup">GtkActionGroup</link>
+ objects. Note that this does not describe the actual
+ "shape" that your menus and toolbars will have; it simply
+ defines the set of commands that will appear in them.
</para>
</listitem>
<listitem>
<para>
Create an XML description of your menus and toolbars for use
- with #GtkUIManager. This defines the actual shape of the
- menus and toolbars.
+ with <link linkend="GtkUIManager">GtkUIManager</link>. This
+ defines the actual shape of the menus and toolbars.
</para>
</listitem>
<listitem>
<para>
Port the code that uses gnome-app and gnome-app-helper to
- #GtkAction and #GtkUIManager.
+ <link linkend="GtkAction">GtkAction</link> and <link
+ linkend="GtkUIManager">GtkUIManager</link>.
</para>
</listitem>
</orderedlist>
The following code is the set of actions that are present in
the <link linkend="gnomeuiinfo-example">previous
example</link>. Note that the toggle and radio entries are
- separate from normal actions. Also, note that #GtkActionEntry
- structures take key names in the format of
- gdk_accelerator_parse() rather than key values plus modifiers;
- you will have to convert these values by hand. For example,
- <constant>GDK_F11</constant> with no modifiers is equivalent
- to a key name of <literal>"F11"</literal>. Likewise,
- <literal>"o"</literal> with
- <constant>GDK_CONTROL_MASK</constant> is equivalent to
+ separate from normal actions. Also, note that <link
+ linkend="GtkActionEntry">GtkActionEntry</link> structures take
+ key names in the format of gdk_accelerator_parse() rather than
+ key values plus modifiers; you will have to convert these
+ values by hand. For example, <constant>GDK_F11</constant>
+ with no modifiers is equivalent to a key name of
+ <literal>"F11"</literal>. Likewise, <literal>"o"</literal>
+ with <constant>GDK_CONTROL_MASK</constant> is equivalent to
<literal>"<ontrol>O"</literal>.
</para>
<para>
After extracting the actions, you will need to create an XML
description of the actual layout of your menus and toolbars
- for use with #GtkUIManager. The following code shows a simple
- menu bar that corresponds to the <link
- linkend="gnomeuiinfo-example">previous example</link>. Note
- that the <guimenu>File</guimenu> and <guimenu>View</guimenu>
- menus have their names specified in the <link
- linkend="gnomeuiinfo-action-entries">action entries</link>,
- not in the XML itself. This is because the XML description
- only contains <emphasis>identifiers</emphasis> for the items
- in the GUI, rather than human-readable names.
+ for use with <link linkend="GtkUIManager">GtkUIManager</link>.
+ The following code shows a simple menu bar that corresponds to
+ the <link linkend="gnomeuiinfo-example">previous
+ example</link>. Note that the <guimenu>File</guimenu> and
+ <guimenu>View</guimenu> menus have their names specified in
+ the <link linkend="gnomeuiinfo-action-entries">action
+ entries</link>, not in the XML itself. This is because the
+ XML description only contains <emphasis>identifiers</emphasis>
+ for the items in the GUI, rather than human-readable names.
</para>
<programlisting>
<title>Creating the Menu Bar</title>
<para>
- In this last example, we will create a #GtkActionGroup based
- on the <link linkend="gnomeuiinfo-action-entries">action
- entries</link> we created above. We will then create a
- #GtkUIManager with the <link linkend="gnomeuiinfo-xml">XML
- description</link> of the menu layout. We will also extract
- the accelerator group and the widgets from the #GtkUIManager
- put them into a window.
+ In this last example, we will create a <link
+ linkend="GtkActionGroup">GtkActionGroup</link> based on the
+ <link linkend="gnomeuiinfo-action-entries">action
+ entries</link> we created above. We will then create a <link
+ linkend="GtkUIManager">GtkUIManager</link> with the <link
+ linkend="gnomeuiinfo-xml">XML description</link> of the menu
+ layout. We will also extract the accelerator group and the
+ widgets from the <link
+ linkend="GtkUIManager">GtkUIManager</link> put them into a
+ window.
</para>
<programlisting>
<title>Migrating from GtkFileSelection to GtkFileChooser</title>
<para>
- #GtkFileChooser, starting with GTK+ 2.4, is the new set of APIs
- for file selection widgets and dialogs. Previous versions of GTK+
- used #GtkFileSelection, which has numerous problems.
+ <link linkend="GtkFileChooser">GtkFileChooser</link>, starting
+ with GTK+ 2.4, is the new set of APIs for file selection widgets
+ and dialogs. Previous versions of GTK+ used <link
+ linkend="GtkFileSelection">GtkFileSelection</link>, which has
+ numerous problems.
</para>
<para>
- #GtkFileChooser is an abstract interface that can be implemented
- by widgets that perform file selection tasks. Two widgets in GTK+
- implement this interface: #GtkFileChooserDialog and
- #GtkFileChooserWidget. Most applications simply need to use
- #GtkFileChooserDialog, which is a dialog box that allows the user
- to select existing files for opening them, or to pick new
- filenames for saving documents. #GtkFileChooserWidget is for
- special applications that need to embed a file selection widget
- inside a larger window. In the context of GTK+,
- #GtkFileChooserDialog is simply a #GtkDialog box with a
- #GtkFileChooserWidget inside.
+ <link linkend="GtkFileChooser">GtkFileChooser</link> is an
+ abstract interface that can be implemented by widgets that perform
+ file selection tasks. Two widgets in GTK+ implement this
+ interface: <link
+ linkend="GtkFileChooserDialog">GtkFileChooserDialog</link> and
+ <link linkend="GtkFileChooserWidget">GtkFileChooserWidget</link>.
+ Most applications simply need to use <link
+ linkend="GtkFileChooserDialog">GtkFileChooserDialog</link>, which
+ is a dialog box that allows the user to select existing files for
+ opening them, or to pick new filenames for saving documents.
+ <link linkend="GtkFileChooserWidget">GtkFileChooserWidget</link>
+ is for special applications that need to embed a file selection
+ widget inside a larger window. In the context of GTK+, <link
+ linkend="GtkFileChooserDialog">GtkFileChooserDialog</link> is
+ simply a <link linkend="GtkDialog">GtkDialog</link> box with a
+ <link linkend="GtkFileChooserWidget">GtkFileChooserWidget</link>
+ inside.
</para>
<section id="gtkfilechooser-creating">
<title>Creating a GtkFileChooserDialog</title>
<para>
- To create a #GtkFileChooserDialog, you simply call
- gtk_file_chooser_dialog_new(). This function is similar to
- gtk_dialog_new() in that it takes parameters for the title
- of the dialog box and its transient parent, as well as its
+ To create a <link
+ linkend="GtkFileChooserDialog">GtkFileChooserDialog</link>, you
+ simply call gtk_file_chooser_dialog_new(). This function is
+ similar to gtk_dialog_new() in that it takes parameters for the
+ title of the dialog box and its transient parent, as well as its
buttons. In addition, it takes in an argument that determines
whether the file chooser dialog will be used for opening
existing files or for saving to a possibly new file.
<title>Selection Modes</title>
<para>
- #GtkFileChooser can be used in two modes, to select a single
- file at a time or to select a set of more than one file. To set
- this, use gtk_file_chooser_set_select_multiple(). In
- single-selection mode, you can use
- gtk_file_chooser_get_filename() to get a file name from the
- local file system or gtk_file_chooser_get_uri() to get a
- full-formed URI. In multiple-selection mode, you can use
- gtk_file_chooser_get_filenames() to get a #GSList of filename
- strings, or gtk_file_chooser_get_uris() to get a list of URI
- strings.
+ <link linkend="GtkFileChooser">GtkFileChooser</link> can be used
+ in two modes, to select a single file at a time or to select a
+ set of more than one file. To set this, use
+ gtk_file_chooser_set_select_multiple(). In single-selection
+ mode, you can use gtk_file_chooser_get_filename() to get a file
+ name from the local file system or gtk_file_chooser_get_uri() to
+ get a full-formed URI. In multiple-selection mode, you can use
+ gtk_file_chooser_get_filenames() to get a <link
+ linkend="GSList">GSList</link> of filename strings, or
+ gtk_file_chooser_get_uris() to get a list of URI strings.
</para>
<para>
- Also, you can configure #GtkFileChooser to select files or
- folders. Consider a backup program that needs to let the user
- select a folder that will be backed up along with its
- subfolders. To configure whether #GtkFileChooser is used to
- select files or folders, use gtk_file_chooser_set_action(). In
+ Also, you can configure <link
+ linkend="GtkFileChooser">GtkFileChooser</link> to select files
+ or folders. Consider a backup program that needs to let the
+ user select a folder that will be backed up along with its
+ subfolders. To configure whether <link
+ linkend="GtkFileChooser">GtkFileChooser</link> is used to select
+ files or folders, use gtk_file_chooser_set_action(). In
addition, this lets you configure whether the file chooser will
be used to select existing files or folders (e.g. for
"File/Open"), or to type in new filenames (for
<para>
Many applications need to have a preview facility within their
file chooser dialogs. Previous to GTK+ 2.4, one needed to
- access the #GtkFileSelection widget hierarchy directly to hook
- in a preview widget. With #GtkFileChooser, there is a dedicated
- API to do this.
+ access the <link
+ linkend="GtkFileSelection">GtkFileSelection</link> widget
+ hierarchy directly to hook in a preview widget. With <link
+ linkend="GtkFileChooser">GtkFileChooser</link>, there is a
+ dedicated API to do this.
</para>
<para>
<title>New features</title>
<para>
- New features in #GtkFileChooser include the following:
+ New features in <link
+ linkend="GtkFileChooser">GtkFileChooser</link> include the
+ following:
</para>
<itemizedlist>
<listitem>
<para>
Ability to select URIs rather than just local files. You
- must use a #GtkFileSystem implementation that supports this,
- for example GtkFileSystemGnomeVFS.
+ must use a <link
+ linkend="GtkFileSystem">GtkFileSystem</link> implementation
+ that supports this, for example the gnome-vfs backend.
</para>
</listitem>
</itemizedlist>
<para>
- To see how to use these features, please consult the
- #GtkFileChooser reference documentation.
+ To see how to use these features, please consult the <link
+ linkend="GtkFileChooser">GtkFileChooser</link> reference
+ documentation.
</para>
</section>
</chapter>
projects / gtk4.git / commitdiff